/*
  Copyright (c) 2009-2017 Dave Gamble and cJSON contributors

  Permission is hereby granted, free of charge, to any person obtaining a copy
  of this software and associated documentation files (the "Software"), to deal
  in the Software without restriction, including without limitation the rights
  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  copies of the Software, and to permit persons to whom the Software is
  furnished to do so, subject to the following conditions:

  The above copyright notice and this permission notice shall be included in
  all copies or substantial portions of the Software.

  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  THE SOFTWARE.
*/

/* 
 * cJSON Utilities Header File - Provides advanced JSON manipulation utilities
 * This header defines utility functions for JSON Pointer, JSON Patch, and JSON Merge Patch operations
 * Implements IETF RFC standards for JSON document transformation and querying
 * Builds upon the core cJSON library to provide standardized JSON manipulation capabilities
 */

#ifndef cJSON_Utils__h
#define cJSON_Utils__h

/* 
 * C++ compatibility declaration for external linkage
 * Ensures proper name mangling when used in C++ programs
 * Maintains C-style function naming when included in C++ compilation units
 */
#ifdef __cplusplus
extern "C"
{
#endif

/* 
 * Include the core cJSON library header file
 * Provides fundamental JSON data structures and basic manipulation functions
 * Required dependency for all utility functions defined in this header
 */
#include "cJSON.h"

/* 
 * JSON Pointer Implementation (RFC 6901) - JSON document querying specification
 * These functions provide standardized JSON Pointer resolution for navigating JSON structures
 * Allow extraction of specific elements from complex JSON documents using pointer syntax
 */

/* 
 * Resolve JSON Pointer expression against target JSON object (case-insensitive)
 * This function implements RFC 6901 JSON Pointer specification for document navigation
 * Supports both absolute and relative pointer expressions with reference tokens
 * Provides case-insensitive member name matching for flexible pointer resolution
 * 
 * @param object Root JSON object to resolve pointer against
 * @param pointer JSON Pointer string following RFC 6901 syntax
 * @return cJSON* Pointer to resolved JSON element or NULL if not found
 */
CJSON_PUBLIC(cJSON *) cJSONUtils_GetPointer(cJSON * const object, const char *pointer);

/* 
 * Resolve JSON Pointer expression with case-sensitive member matching
 * Enhanced version of GetPointer that maintains exact case sensitivity for member names
 * Provides stricter pointer resolution for systems requiring precise key matching
 * Useful for JSON documents with case-sensitive key requirements
 * 
 * @param object Root JSON object to resolve pointer against
 * @param pointer JSON Pointer string following RFC 6901 syntax
 * @return cJSON* Pointer to resolved JSON element or NULL if not found
 */
CJSON_PUBLIC(cJSON *) cJSONUtils_GetPointerCaseSensitive(cJSON * const object, const char *pointer);

/* 
 * JSON Patch Implementation (RFC 6902) - JSON document transformation specification
 * These functions provide standardized JSON Patch operations for modifying JSON documents
 * Support atomic application of multiple operations to transform JSON structures
 */

/* 
 * Generate JSON Patch array describing transformations between two JSON objects (case-insensitive)
 * This function implements RFC 6902 JSON Patch specification for change description
 * Computes minimal sequence of operations to transform 'from' object into 'to' object
 * NOTE: This modifies objects in 'from' and 'to' by sorting the elements by their key
 * Sorting ensures consistent patch generation regardless of original member order
 * 
 * @param from Source JSON object representing initial state
 * @param to Target JSON object representing desired final state
 * @return cJSON* JSON Patch array containing transformation operations
 */
CJSON_PUBLIC(cJSON *) cJSONUtils_GeneratePatches(cJSON * const from, cJSON * const to);

/* 
 * Generate JSON Patch array with case-sensitive member comparison
 * Enhanced version of GeneratePatches that maintains exact case sensitivity
 * Provides stricter patch generation for systems requiring precise key matching
 * NOTE: This modifies objects in 'from' and 'to' by sorting the elements by their key
 * 
 * @param from Source JSON object representing initial state
 * @param to Target JSON object representing desired final state
 * @return cJSON* JSON Patch array containing transformation operations
 */
CJSON_PUBLIC(cJSON *) cJSONUtils_GeneratePatchesCaseSensitive(cJSON * const from, cJSON * const to);

/* 
 * Utility function for manually constructing JSON Patch array entries
 * This helper function creates individual patch operation objects for custom patch construction
 * Allows manual creation of specific patch operations outside automatic patch generation
 * Useful for building custom transformation sequences or specialized patch operations
 * 
 * @param array Target patch array to add the operation to
 * @param operation Patch operation type ("add", "remove", "replace", "move", "copy", "test")
 * @param path JSON Pointer path specifying target location for operation
 * @param value JSON value to use for add/replace operations (NULL for remove operations)
 */
CJSON_PUBLIC(void) cJSONUtils_AddPatchToArray(cJSON * const array, const char * const operation, const char * const path, const cJSON * const value);

/* 
 * Apply JSON Patch operations to target JSON object (case-insensitive)
 * This function executes a sequence of patch operations to transform the target object
 * Implements RFC 6902 compliant patch application with error checking and validation
 * Returns 0 for success and non-zero for application failures
 * NOTE: ApplyPatches is NOT atomic on failure - partial application may occur
 * 
 * @param object Target JSON object to apply patches to
 * @param patches JSON array containing patch operations to apply
 * @return int 0 for successful application, error code for failures
 */
CJSON_PUBLIC(int) cJSONUtils_ApplyPatches(cJSON * const object, const cJSON * const patches);

/* 
 * Apply JSON Patch operations with case-sensitive member matching
 * Enhanced version of ApplyPatches that maintains exact case sensitivity
 * Provides stricter patch application for systems requiring precise key matching
 * Returns 0 for success and non-zero for application failures
 * NOTE: ApplyPatches is NOT atomic on failure - partial application may occur
 * 
 * @param object Target JSON object to apply patches to
 * @param patches JSON array containing patch operations to apply
 * @return int 0 for successful application, error code for failures
 */
CJSON_PUBLIC(int) cJSONUtils_ApplyPatchesCaseSensitive(cJSON * const object, const cJSON * const patches);

/*
// Note that ApplyPatches is NOT atomic on failure. To implement an atomic ApplyPatches, use:
//int cJSONUtils_AtomicApplyPatches(cJSON **object, cJSON *patches)
//{
//    cJSON *modme = cJSON_Duplicate(*object, 1);
//    int error = cJSONUtils_ApplyPatches(modme, patches);
//    if (!error)
//    {
//        cJSON_Delete(*object);
//        *object = modme;
//    }
//    else
//    {
//        cJSON_Delete(modme);
//    }
//
//    return error;
//}
// Code not added to library since this strategy is a LOT slower.
*/

/* 
 * JSON Merge Patch Implementation (RFC 7386) - Simplified JSON document merging
 * These functions provide JSON Merge Patch operations for streamlined document modification
 * Offer simpler alternative to JSON Patch with more intuitive modification semantics
 */

/* 
 * Apply JSON Merge Patch to target JSON object (case-insensitive)
 * This function implements RFC 7386 JSON Merge Patch specification for document merging
 * Modifies target object by applying patch according to merge patch semantics
 * Returns modified target object pointer (may be same as input or newly allocated)
 * Merge patch provides simpler alternative to JSON Patch for common modification scenarios
 * 
 * @param target JSON object to be modified by the merge patch
 * @param patch JSON merge patch object containing desired modifications
 * @return cJSON* Pointer to modified target object (may be original or new object)
 */
CJSON_PUBLIC(cJSON *) cJSONUtils_MergePatch(cJSON *target, const cJSON * const patch);

/* 
 * Apply JSON Merge Patch with case-sensitive member matching
 * Enhanced version of MergePatch that maintains exact case sensitivity
 * Provides stricter patch application for systems requiring precise key matching
 * Returns modified target object pointer (may be same as input or newly allocated)
 * 
 * @param target JSON object to be modified by the merge patch
 * @param patch JSON merge patch object containing desired modifications
 * @return cJSON* Pointer to modified target object (may be original or new object)
 */
CJSON_PUBLIC(cJSON *) cJSONUtils_MergePatchCaseSensitive(cJSON *target, const cJSON * const patch);

/* 
 * Generate a JSON Merge Patch describing transformations between two JSON objects (case-insensitive)
 * This function creates a merge patch that can transform 'from' object into 'to' object
 * Implements RFC 7386 merge patch generation with minimal change representation
 * NOTE: This modifies objects in 'from' and 'to' by sorting the elements by their key
 * Sorting ensures consistent patch generation regardless of original member order
 * 
 * @param from Source JSON object representing initial state
 * @param to Target JSON object representing desired final state
 * @return cJSON* JSON Merge Patch object describing required transformations
 */
CJSON_PUBLIC(cJSON *) cJSONUtils_GenerateMergePatch(cJSON * const from, cJSON * const to);

/* 
 * Generate a JSON Merge Patch with case-sensitive member comparison
 * Enhanced version of GenerateMergePatch that maintains exact case sensitivity
 * Provides stricter patch generation for systems requiring precise key matching
 * NOTE: This modifies objects in 'from' and 'to' by sorting the elements by their key
 * 
 * @param from Source JSON object representing initial state
 * @param to Target JSON object representing desired final state
 * @return cJSON* JSON Merge Patch object describing required transformations
 */
CJSON_PUBLIC(cJSON *) cJSONUtils_GenerateMergePatchCaseSensitive(cJSON * const from, cJSON * const to);

/* 
 * JSON Pointer Resolution Utilities - Advanced pointer manipulation functions
 * These functions provide additional pointer-related utilities beyond basic resolution
 */

/* 
 * Construct JSON Pointer from root object to target object
 * This function generates a JSON Pointer string that references the target object from the root
 * Traverses the JSON structure to find the path from root to target object
 * Returns allocated string containing the pointer path (caller must free)
 * Useful for generating references to specific elements within complex JSON structures
 * 
 * @param object Root JSON object to start pointer construction from
 * @param target Target JSON object to find pointer path to
 * @return char* Allocated string containing JSON Pointer path (must be freed by caller)
 */
CJSON_PUBLIC(char *) cJSONUtils_FindPointerFromObjectTo(const cJSON * const object, const cJSON * const target);

/* 
 * JSON Object Sorting Utilities - Member organization functions
 * These functions provide object member sorting for consistent JSON serialization
 */

/* 
 * Sort object members into alphabetical order (case-insensitive)
 * This function reorganizes object members into consistent alphabetical ordering
 * Improves JSON serialization consistency and facilitates comparison operations
 * Modifies the object in-place by reordering member linked list
 * 
 * @param object JSON object to have its members sorted alphabetically
 */
CJSON_PUBLIC(void) cJSONUtils_SortObject(cJSON * const object);

/* 
 * Sort object members with case-sensitive alphabetical ordering
 * Enhanced version of SortObject that maintains exact case sensitivity
 * Provides stricter sorting for systems requiring precise key ordering
 * Modifies the object in-place by reordering member linked list
 * 
 * @param object JSON object to have its members sorted alphabetically
 */
CJSON_PUBLIC(void) cJSONUtils_SortObjectCaseSensitive(cJSON * const object);

/* 
 * C++ compatibility declaration termination
 * Closes the extern "C" block started at the beginning of the file
 * Ensures proper C++ name mangling restoration after utility declarations
 */
#ifdef __cplusplus
}
#endif

#endif

